Hooks

Overview

This document provides comprehensive information about the hooks configuration in the VFD Providers application. Hooks are integration points that allow the app to interact with the Frappe framework and extend functionality of existing DocTypes.

Hooks File Location

File: apps/vfd_providers/vfd_providers/hooks.py

Application Metadata

Basic Information

app_name = "vfd_providers"
app_title = "VFD Providers"
app_publisher = "Aakvatech Limited"
app_description = "VFD Providers"
app_email = "info@aakvatech.com"
app_license = "GPL"

Purpose: Defines the application identity and metadata used by the Frappe framework.

Client-Side Integrations

DocType JavaScript Files

doctype_js = {
    "Sales Invoice": "utils/sales_invoice.js",
    "Customer": "utils/customer.js",
}

Sales Invoice JavaScript

File: apps/vfd_providers/vfd_providers/utils/sales_invoice.js Purpose: Enhances Sales Invoice form with VFD-specific functionality

Key Features:

VFD generation button handling
Form field validations
Customer ID type auto-population
VFD status display enhancements

Customer JavaScript

File: apps/vfd_providers/vfd_providers/utils/customer.js Purpose: Enhances Customer form with VFD-specific functionality

Key Features:

VFD customer ID validation
Tax ID formatting
Customer ID type selection logic

Server-Side Event Hooks

Document Events Configuration

doc_events = {
    "Sales Invoice": {
        "on_submit": "vfd_providers.utils.utils.autogenerate_vfd",
        "before_cancel": "vfd_providers.utils.sales_invoice.validate_cancel",
        "before_submit": "vfd_providers.utils.sales_invoice.vfd_validation",
    },
    "Customer": {
        "validate": "vfd_providers.utils.utils.clean_and_update_tax_id_info",
    },
}

Sales Invoice Events

1. on_submit Event

Function: vfd_providers.utils.utils.autogenerate_vfd Trigger: After Sales Invoice is successfully submitted Purpose: Automatically generates VFD receipt if auto-generation is enabled

Business Logic:

Checks if invoice is eligible for VFD processing
Verifies auto-generation flag is enabled
Calls appropriate VFD provider API
Updates invoice with VFD response data

2. before_cancel Event

Function: vfd_providers.utils.sales_invoice.validate_cancel Trigger: Before Sales Invoice cancellation is processed Purpose: Prevents cancellation of invoices already sent to TRA

Validation Rules:

Checks if VFD receipt number (vfd_rctvnum) exists
Throws error if invoice is already registered with TRA
Ensures compliance with tax authority requirements

3. before_submit Event

Function: vfd_providers.utils.sales_invoice.vfd_validation Trigger: Before Sales Invoice submission is processed Purpose: Validates VFD-related data and requirements

Validation Checks:

Ensures base net total is not zero
Validates tax configuration
Checks customer VFD ID information
Verifies VFD provider settings

Customer Events

1. validate Event

Function: vfd_providers.utils.utils.clean_and_update_tax_id_info Trigger: During Customer document validation Purpose: Cleans and standardizes tax ID information for VFD compliance

Processing Logic:

Removes non-numeric characters from tax ID
Sets VFD customer ID type based on tax ID presence
Assigns default customer ID for customers without tax ID
Ensures VFD compliance for all customer records

Scheduled Tasks

Cron Job Configuration

scheduler_events = {
    "cron": {
        "*/10 * * * *": [
            "vfd_providers.vfd_providers.doctype.simplify_vfd_settings.simplify_vfd_settings.get_token"
        ],
        "*/15 * * * *": [
            "vfd_providers.utils.utils.posting_all_vfd_invoices",
        ],
    }
}

Token Refresh Task

Schedule: Every 10 minutes (*/10 * * * *) Function: simplify_vfd_settings.get_token Purpose: Automatically refreshes authentication tokens for SimplifyVFD provider

Functionality:

Checks token expiration for all SimplifyVFD settings
Refreshes expired tokens automatically
Maintains continuous API connectivity
Prevents authentication failures during VFD posting

VFD Invoice Posting Task

Schedule: Every 15 minutes (*/15 * * * *) Function: vfd_providers.utils.utils.posting_all_vfd_invoices Purpose: Automatically posts pending VFD invoices to tax authorities